From 51116ad493ad4a6d101b01ad7aec1951cdbcb6aa Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Thu, 22 Jan 2004 20:17:34 +0000 Subject: [PATCH] New chapter with a "Migration Checklist" of things people need to do to be 2004-01-22 Federico Mena Quintero * gtk/migrating-checklist.sgml: New chapter with a "Migration Checklist" of things people need to do to be good citizens in the GTK+ world. This is mainly a way to tell people about interesting APIs that they should use instead of hand-hacked approaches. * gtk/gtk-docs.sgml: Added migrating-checklist.sgml. * gtk/Makefile.am (content_files): Likewise. --- docs/reference/ChangeLog | 11 ++ docs/reference/gtk/Makefile.am | 1 + docs/reference/gtk/gtk-docs.sgml | 2 + docs/reference/gtk/migrating-checklist.sgml | 141 ++++++++++++++++++++ 4 files changed, 155 insertions(+) create mode 100644 docs/reference/gtk/migrating-checklist.sgml diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 8488675ac8..21e71de682 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,14 @@ +2004-01-22 Federico Mena Quintero + + * gtk/migrating-checklist.sgml: New chapter with a "Migration + Checklist" of things people need to do to be good citizens in the + GTK+ world. This is mainly a way to tell people about interesting + APIs that they should use instead of hand-hacked approaches. + + * gtk/gtk-docs.sgml: Added migrating-checklist.sgml. + + * gtk/Makefile.am (content_files): Likewise. + Thu Jan 22 01:46:45 2004 Jonathan Blandford * gtk/tmpl/gtktreemodelsort.sgml: new introduction section. diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 0c7534d97c..a40008fa1a 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -87,6 +87,7 @@ content_files = \ changes-2.0.sgml \ compiling.sgml \ framebuffer.sgml \ + migrating-checklist.sgml \ migrating-GtkAction.sgml \ migrating-GtkFileChooser.sgml \ objects_grouped.sgml \ diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 2632b9057d..5c14e72d62 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -179,6 +179,7 @@ + @@ -541,6 +542,7 @@ that is, GUI components such as GtkButton or + >k-migrating-checklist; >k-Changes-1-2; >k-Changes-2-0; >k-migrating-GtkFileChooser; diff --git a/docs/reference/gtk/migrating-checklist.sgml b/docs/reference/gtk/migrating-checklist.sgml new file mode 100644 index 0000000000..51a1e9b316 --- /dev/null +++ b/docs/reference/gtk/migrating-checklist.sgml @@ -0,0 +1,141 @@ + + Migration Checklist + + + This chapter includes a checklist of things you need to do to + ensure that your programs are good citizens in the GTK+ world. By + paying attention to the points in the checklist, you ensure that + many automatic features of GTK+ will work correctly in your + program. + + +
+ Implement GtkWidget::popup_menu + + + Why + + By handling this signal, you let widgets have + context-sensitive menus that can be invoked with the standard + key bindings. + + + + + The GtkWidget::popup_menu + signal instructs the widget for which it is emitted to create a + context-sensitive popup menu. By default, the key binding mechanism is set to + emit this signal when the + ShiftF10 + or Menu keys are pressed while a widget has the + focus. If a widget in your application shows a popup menu when + you press a mouse button, you can make it work as well through + the normal key binding mechanism in the following fahion: + + + + + + Write a function to create and show a popup menu. This + function needs to know the button number and the event's + time to pass them to gtk_menu_popup(). You can implement + such a function like this: + + + +static void +do_popup_menu (GtkWidget *my_widget, GdkEventButton *event) +{ + GtkWidget *menu; + int button, event_time; + + menu = gtk_menu_new (); + g_signal_connect (menu, "deactivate", + G_CALLBACK (gtk_widget_destroy), NULL); + + /* ... add menu items ... */ + + if (event) + { + button = event->button; + event_time = event->time; + } + else + { + button = 0; + event_time = gtk_get_current_event_time (); + } + + gtk_menu_popup (GTK_MENU (popup), NULL, NULL, NULL, NULL, + button, event_time); +} + + + + + + In your button_press handler, call this function when you + need to pop up a menu: + + + +static gboolean +my_widget_button_press_event_handler (GtkWidget *widget, GdkEventButton *event) +{ + /* Ignore double-clicks and triple-clicks */ + if (event->button == 3 && event->type == GDK_BUTTON_PRESS) + { + do_popup_menu (widget, event); + return TRUE; + } + + return FALSE; +} + + + + + + Implement a handler for the popup_menu signal: + + + +static gboolean +my_widget_popup_menu_handler (GtkWidget *widget) +{ + do_popup_menu (widget, NULL); + return TRUE; +} + + + + + + + If you do not pass a positioning function to gtk_menu_popup(), + it will show the menu at the mouse position by default. This + is what you usually want when the menu is shown as a result of + pressing a mouse button. However, if you press the + ShiftF10 + or Menu keys while the widget is focused, the + mouse cursor may not be near the widget at all. In the example above, you may want to + provide your own menu-positioning function + in the case where the event is + NULL. This function should compute the + desired position for a menu when it is invoked through the + keyboard. + + +
+ + + -- 2.30.2